<html>
<!-- $Id: jena-faq.html,v 1.65 2009/10/13 11:42:05 andy_seaborne Exp $ -->
<!-- (c) Copyright 2003, 2004, 2005, 2006, 2007, 2008, 2009 Hewlett-Packard Development Company LP -->
<head>
  <title>Jena - FAQ</title>
  <meta name="author" content="The Jena Team" />
  <meta name="description" content="Frequently asked questions about the Jena 2 semantic web toolkit" />
  <meta name="keywords" content="Jena, Jena2, FAQ, Java, semantic web, RDF, OWL" />


  <link rel="stylesheet" type="text/css" href="styles/site.css" />
</head>

<body>

<div id="header">
Jena 2 &ndash; Frequently Asked Questions
</div>


<div id="main">

<table width="100%" cellspacing="0" cellpadding="0">
<tr>

<!-- Left -->
<td width="25ex" style="border-right: 1px solid #DDD;">
 <div id="leftnav">
  <div align="center" >
  <img src="images/jena-logo-small.png" alt="jena logo" style="border:0;" />
  </div>
  <div class="grouptitle" style="width: 20ex;">on this site</div>
  <div class="item"><a href="index.html">home</a></div>
  <div class="item"><a href="downloads.html">downloads</a></div>
  <div class="item"><a href="license.html">license</a></div>
  <div class="item"><a href="documentation.html">documentation</a></div>
  <div class="item"><a href="support.html">support</a></div>
  <div class="item"><a href="resources.html">resources</a></div>
  <div class="item"><a href="contrib/contributions.html">contributions</a></div>
  <div class="item">&nbsp;</div>

  <div id="localnav">
    <div class="item">&nbsp;</div>
    <div class="item">&nbsp;</div>
    <div class="item">&nbsp;</div>
    <div class="item">&nbsp;</div>
    <div class="item">&nbsp;</div>
    <div class="item">&nbsp;</div>
  </div>
 </div>
</td>

<!-- Right -->
<td width="100%"> <!-- Set width.  Fixed width above takes precedence : fixes Mozilla oddity -->

<div id="trail">
<a href="index.html">home</a>
&raquo; <a href="documentation.html">documentation</a>
&raquo; <a href="jena-faq.html">faq</a>
</div>

<div id="content">

<h2>Index</h2>
<h3>General</h3>
<ul>
  <li><a href="#general-0">Why do I get a <code>java.lang.NoClassDefFoundError</code> when I run a Jena application?</a></li>
  <li><a href="#general-1">What does the error '<code>java.lang.NoSuchFieldError: actualValueType</code>' mean?</a></li>
  <li><a href="#general-2">What versions of library jars does Jena require?</a></li>
  <li><a href="#general-3">How do I get the most up-to-date version of Jena?</a></li>
  <li><a href="#general-4">How do I reduce the space needed to deploy Jena?</a></li>
</ul>
<h3>RDF model API</h3>
<ul>
      <li><a href="#api-0">Why does the localname part of my URI look wrong?</a></li>
      <li><a href="#api-1">How do I change the URI or localName of a Resource?</a></li>
      <li><a href="#api-2">Why do I see the warning message <i>'Detected a NaN anomaly believed to be due to use of JDK 1.4.1'</i>?</a></li>
</ul>
<h3>Reasoner and inference models</h3>
<ul>
  <li><a href="#reasoner-0">I want to develop my own rules, how do I get started?</a></li>
  <li><a href="#reasoner-1">Why are there two different arrows ( -&gt; and &lt;- ) in the rule syntax?</a></li>
  <li><a href="#reasoner-2">The domain and range inferences look wrong, is that a bug?</a></li>
  <li><a href="#reasoner-3">Why do I get a warning: <i>Creating OWL rule reasoner working over another OWL rule reasoner</i></a></li>
  <li><a href="#reasoner-4">Why do I get out of memory errors when working with the wine ontology?</a></li>
  <li><a href="#reasoner-5">What causes the error
    &quot;<code>java.lang.UnsupportedOperationException: this is not a URI node</code>&quot;
    in the DIG reasoner?</a></li>
  <li><a href="#reasoner-6">I want to use my own custom rules to extend an existing RDFS or OWL
Schema, what do I do?</a></li>
</ul>
<h3>Ontology API</h3>
<ul>
  <li><a href="#ontology-0">Why doesn't <code>listClasses()</code> (<code>listProperties()</code>
      / <code>listIndividuals()</code>, etc) work?</a></li>
  <li><a href="#ontology-1">Why doesn't <code>listProperties()</code> return any results when <code>listObjectProperties()</code> (or
      <code>listDatatypeProperties()</code>) does?</a></li>
  <li><a href="#ontology-2">Why are my transitive properties (or symmetric properties or inverse functional
      properties) missing when I call <code>listObjectProperties()</code>?</a></li>
  <li><a href="#ontology-3">Why does <code>.as(&nbsp;OntProperty.class&nbsp;)</code> fail with
    <code>ConversionException</code> on SymmetricProperty (or other property types)?</a></li>
  <li><a href="#ontology-4">Why doesn't the ontology API handle <code>sub-class</code>
         (or <code>sub-property</code>, <code>domain</code>, <code>range</code>, etc)
         relationships in a DAML model?</a></li>
  <li><a href="#ontology-5">I don't understand very clearly the difference between
         the various <code>OntModel</code> model profiles.</a></li>
</ul>
<h3>Database and persistence</h3>
<ul>
  <li><a href="#db-0">Why do I get an exception when trying to create a new persistent model?</a></li>
  <li><a href="#db-1">Why do I run out of memory when trying to list statements in a persistent
  model?</a></li>
  <li><a href="#db-2">Has Jena2 persistence been ported to other database engines and platforms
  besides those officially supported?</a></li>
  <li><a href="#db-3">Is there a limit on the number of models in a database?</a></li>
  <li><a href="#db-4" name="dblock">Why am I getting an exception on failure to lock or unlock the database?</a></li>
  <li><a href="#db-5">How do I access the Jena database tables?</a></li>

</ul>
<h3>XML serialisation (reading and writing)</h3>
<ul>
  <li><a href="#xml-1">Why does my output use <code>&lt;rdf:Description&nbsp;...&gt;</code>
    when I want output like <code>&lt;owl:Class&nbsp;...&gt;</code>?</a></li>
  <li><a href="#xml-2">Why does my XML output contain strange prefixes <code>j.0</code>,
  <code>j.1</code>, etc?</a></li>
</ul>

<h3>SPARQL and query processing</h3>
<p>See the <a href="http://openjena.org/ARQ/documentation.html">ARQ documentation</a> and
<a href="http://openjena.org/ARQ/FAQ.html">ARQ FAQ</a>. See also the
<a href="http://openjena.org/ARQ/">ARQ web site</a> for new versions of
ARQ.</p>
<ul>
  <li><a href="#sparql-0">How do I do test for substrings of literals?</a></li>
</ul>


<h2>Answers</h2>
<h3>General</h3>

<p id="general-0"><strong>Q: Why do I get a <code>java.lang.NoClassDefFoundError</code> when I run a Jena application?</strong><br>
  <strong>A:</strong> This means that one or more of the libraries that Jena depends on is not
  on your classpath. Typically, all of the libraries (.jar files) in <code>$JENA/lib</code>,
  where <code>$JENA</code> refers to the directory in which you installed Jena, should be on
  your classpath. Consult the documentation for your JDK for details on setting
  the classpath for your system. There are also a number of on-line tutorials for setting
  the Java classpath. Consult Google or see
      <a href="http://www.dynamic-apps.com/tutorials/classpath.jsp">here</a>.</p>

<p id="general-1"><strong>Q: What does the error '<code>java.lang.NoSuchFieldError: actualValueType</code>' mean?</strong><br>
  <strong>A:</strong> This is almost always due to using the wrong version of the Xerces
  library. Jena makes use of XML Schema support that changed at Xerces 2.6.0 and is not
  compatible with earlier versions. At the time of writing Jena ships with Xerces 2.6.1.
  <br />
  In some situations your runtime environment may be picking up an earlier version of Xerces from
  an "endorsed" directory and you will need to either disable use of that endorsed library or replace
  it by a more uptodate version of Xerces. This occurs with tomcat 5.* and certain configurations of jdk 1.4.1.
 </p>

<p id="general-2">
  <strong>Q: What versions of library jars does Jena require?</strong><br />
  <strong>A:</strong> Jena makes use of several third party Java libraries. Copies of
  each of these is included in the $JENA/lib area of the distribution and we recommend
  including all of these jars in your classpath. In some circumstances applications
  already make use of specific versions of these libraries (e.g. Xerces) and
  need to check if the version they are using is compatible with those shipped
  by Jena. The <a href="Licenses/index.html">current library versions used by Jena</a> are given
  <a href="Licenses/index.html">here</a>.</p>

<p id="general-3">
  <strong>Q: How do I get the most up-to-date version of Jena?</strong><br />
  <strong>A:</strong> Released versions of Jena are available from the
  <a href="http://sourceforge.net/project/showfiles.php?group_id=40417">downloads page</a>
  on SourceForge.
  However, there may be changes and bug fixes
  that have been added to the Jena codebase that are not yet available as
  part of a release. To get the most up-to-date version of Jena, download
  the source code from CVS (instructions for this are
  <a href="http://sourceforge.net/cvs/?group_id=40417">available here</a>).
  To compile the source code and generate a new
  <code>jena.jar</code> file,
  <a href="http://ant.apache.org/">Ant</a> must be installed and on the path. The
  command to build Jena is the default Ant target, so it only necessary to
  <code>cd</code> to the Jena root directory, which should contain the file
  <code>build.xml</code>, and issue the command <code>ant</code>.
</p>
<p>
  To test that the new compiled version of Jena is working correctly, run
  the script <code>test.bat</code> (Windows) or <code>test.sh</code> (Linux or
  Cygwin) to run the full suite of Jena regression tests.  There should
  be no test failures. <strong>Note:</strong> however that non-release
  versions of Jena may not be as fully tested and stable as the formal
  releases.
</p>

<p id="general-4">
  <strong>Q: How do I reduce the space needed to deploy Jena (give
  Jena a smaller footprint)?</strong><br />
  <strong>A:</strong> Jena attempts to follow the various relevant specifications
  very closely, which means that both Jena itself, and the libraries
  (.jar files) it depends on, are quite large.  For example, the <code>icu4j</code>
  library assists with the correct interpretation of URI's encoded in international
  character sets. For many applications the size of the Jena deployment
  is not a problem. There are some
  circumstances, however, where reducing the size of the installed libraries is
  important - for example, when installing a semantic web application on a mobile
  device. To reduce the storage space required for Jena itself you can build a
  different version of <code>jena.jar</code>, using the command:
</p>
<pre>    ant jar-optimised</pre>
  <p>This builds a version of Jena with no symbols or other debugging information
  (see above for instructions on using ant).
  Note that this will make error stacktraces less informative.
  </p><p>The library <code>jenatest.jar</code>
  contains Jena's unit test suite. This does not have to be included when deploying
  a Jena application. Other libraries from the Jena lib directory may be left out,
  with caution, if the functionality of that library is not required. For example,
  if the application is <em>only</em> going to handle ascii text, it should not be
  necessary to install the <code>icu4j</code> library. However, users should be
  aware that the only <em>supported</em> configuration of Jena is to deploy with
  all of the .jar files from the <code>lib/</code> directory, except for
  <code>jenatest.jar</code> or an alternative optimised <code>jena.jar</code>.
  Other configurations may well work, but are at the user's
  own risk.
  </p>

    <h3>RDF model API</h3>
    <p id="api-0"><strong>Q. Why does the localname part of my URI look wrong?</strong><br />
      <strong>A:</strong> In Jena it is possible to retrieve the localname part of a Resource or Property
      URI. Sometimes developers create Resources with a full URI reference but
      find that the result of a getLocalName call is not quite what they expected.
      This is usually because the URI is ill-formed or cannot be correctly split
      in the way you expected. The only reason for separating namespace and local
      name is to support the XML serialization in which qnames are used for properties
      and classes. Thus the main requirement of the split is that the localname
      component must be a legal XML NCName. This means it must start with a letter
      or _ character and can only contain limited punctuation. In particular,
      they can't contain spaces, but then spaces are not legal in URI references
      anyway. In general, it is best to not use the localname split to encode
      any information, you should only be concerned with it if you are coding
      a parser or writer.</p>

    <p id="api-1"><strong>Q. How do I change the URI or localName of a Resource?</strong><br />
      <strong>A:</strong> In Jena, the URI of a resource is invariant.
      So there is no <code>setLocalName()</code>, or <code>setURI()</code> method,
      and there will never be one.<br />
      The only way to "rename" a resource is to remove all of the statements that
      mention resource <em>R</em>, add add new statements with <em>R</em> replaced by <em>R'</em>.
      A utility for doing this is provided: <br />
      &nbsp;&nbsp;<code>com.hp.hpl.jena.util.ResourceUtils.renameResource()</code><br />
      If you are working with inference or ontology models, you need to be
      careful to do this on the base model, not the entailment (aka inference) model.
    </p>

    <p id="api-2"><strong>Why do I see the warning message <i>'Detected a NaN anomaly believed to be due to use of JDK 1.4.1'</i>?</strong><br />
      <strong>A:</strong> You're using an obsolete version of Jena and JDK 1.4.1.     
      As a side effect of some changes post-Jena 2.1 we started seeing
      random error message of the form 'Illegal load factor: NaN' when creating a HashMap.
      This appears to be a JDK bug in that the call is perfectly legal and the error
      message is seen frequently under JDK 1.4.1 but
      has never been seen under 1.3.1 or 1.4.2. We provided a work around which simply tries
      again to create the HashMap and this log message indicates that the work around has
      been triggered. Later versions of Jena ceased using that code. 
      </p>
      <p>To prevent it occuring switch to JDK 1.4.2 or later and upgrade your Jena. 
      If you continute to see the message please let us know.
    </p>

<h3>Reasoner and inference models</h3>
  <p id="reasoner-0"><strong>Q. I want to develop my own rules, how do I get started?</strong><br />
    <strong>A:</strong> The GenericRuleReasoner is the place to start. 
    You can create instances of this reasoner by
    supplying either an explicit set of Rule objects 
    or a configuration description (as a Jena Model)
    that points to a local rule file. 
    See the inference documentation for more details: <br />
    <a href="inference/index.html#rules">inference/index.html#rules</a>
  </p>

  <p id="reasoner-1"><strong>Q. Why are there two different arrows ( -&gt; and &lt;- ) in the rule syntax?</strong><br />
    <strong>A:</strong> As explained in the documentation there are two rule systems available - a
    forward chainer and a backward chainer. You can chose to use either or
    use the two together in a hybrid mode. <br />

    So if we use Ti as short hand for triple patterns like (?x rdf:type ?C),
    and if we ignore functors and procedural call out for now, then the syntax:<br />
    <code>&nbsp;&nbsp;&nbsp;&nbsp;    T1, T2, ... TN -> T0 .    </code> <br />
    means that if the triple patterns T1 to TN match in the data set then
    then the triple T0 can be deduced as a consequence. Similarly <br />
    <code> &nbsp;&nbsp;&nbsp;&nbsp;   T0 <- T1, T2, ... TN .    </code> <br />
    means the same thing - the consequence is always on the "pointy" end of
    the arrow. <br />

    Now if you are just using pure forward or backward rules then you could
    chose to use either syntax interchangeably. This allows you to write a
    rule set and use it in either mode. Though in practice "-&gt;" is the more
    conventional direction in forward systems and "&lt;-" is the more
    conventional one in backward systems. <br />

    The hybrid configuration allows you to create new backward rules as a
    result of forward rules firing so that the syntax: <br />
    <code> &nbsp;&nbsp;&nbsp;&nbsp;    T1, T2 -> [T0 <- T3, T4] .     </code> <br />
    Is saying that if both T1 and T2 match in the dataset then add the
    backward rule "[T0 &lt;- T3, T4]" after instantiating any bound variables.
  </p>

  <p id="reasoner-2"><strong>Q. The domain and range inferences look wrong, is that a bug?</strong><br />
      <strong>A:</strong> The way rdfs range and domain declarations work is completely alien to
      anyone who thinks of RDFS and OWL as being a bit like a type system for
      a programming language, especially an object oriented language. Whilst there
      may be bugs in the inference rule sets the most common explanation for surprising
      results, when listing inferred domains and ranges, is this mismatch in expectations.
    <p> Suppose we have three classes <code>eg:Man</code> is an <code>rdfs:subClassOf</code>
      <code>eg:Person</code> is an <code>rdfs:subClassOf</code> <code>eg:Animal</code>.
      Suppose we have a property <code>eg:personalName</code> which is declared to
      have <code>rdfs:domain</code> <code>eg:Person</code>. Now the question is
      what other values can be inferred for the <code>rdfs:domain</code> of <code>eg:personalName</code>?</p>
    <p> In pure RDFS no additional conclusions can be made. The definition of
      domain and range is <i>intensional</i> not <i>extensional</i>. It only works
      forward. Declaring <code>&lt;eg:personalName rdfs:domain eg:Person&gt;</code>
      means that anything to which <code>eg:personalName</code> is applied can
      be concluded to be of type <code>eg:Person</code>. It does not work backward
      - if you somehow knew that all things to which <code>eg:personalName</code>
      applied were also <code>Foo</code>'s you cannot conclude that <code>&lt;eg:personalName
      rdfs:domain Foo&gt;.</code></p>
    <p>However, RDFS permits systems to strengthen the meaning of domain and range
      to be extensional, so that valid domain and range deductions can be made.
      OWL makes use of this option. So in OWL, then in our example we can also
      deduce that <code>&lt;eg:personalName rdfs:domain eg:Animal&gt;</code>.
      If you are used to object oriented programming this may look wrong. It is
      tempting, but incorrect, to think of rdfs:domain as meaning <i>this is the
      class of objects to which this property can be applied. </i>With that mindset
      you might expect to find that <code>&lt;eg:personalName rdfs:domain eg:Man&gt;</code>,
      after all every <code>eg:Man</code> is an <code>eg:Person</code> so it is
      always &quot;legal&quot; to apply <code>eg:personalName</code> to an <code>eg:Man</code>.
      That is true, it is legal, any <code>eg:Man</code> is allowed to have a
      a <code>eg:personalName</code> but <code>rdfs:domain</code> does not describe
      what is legal. The statement <code>&lt;P rdfs:domain C&gt;</code> just means
      <i>all things to which P is applied can be inferred to have class C</i>.
      You can see that if we tried to infer <code>&lt;eg:personalName rdfs:domain
      eg:Man&gt;</code> then we would start concluding that anything with a name
      was a man which is not right - every Man can have a name but non-Man Persons
      are also allowed to have names in this example.</p>

  <p id="reasoner-3"><strong>Q: Why do I get a warning: <i>Creating OWL rule reasoner working over another OWL rule reasoner</i></strong><br />
      <strong>A:</strong> If you create an inference graph explicitly from an OWL reasoner or implicitly
      (by using OntModelSpec.OWL_*_RULE) then it is best if the argument models
      (data and schema) are plain models. It is easy to accidentally misuse the API and
      create an inference model working over the results of another inference model.
      This is a redundancy which significantly affects performance to no useful effect.
      To help detect this situation we have added a warning message. The best way
      to stop the message is to change your model construction code so that only the
      final InfModel/OntModel is specified to use OWL inference. If this is not
      appropriate for some reason you can disable the check and warning messages
      using the global flag <code>com.hp.hpl.jena.shared.impl.JenaParameters.enableOWLRuleOverOWLRuleWarnings.</code></p>


  <p id="reasoner-4"><strong>Q: Why do I get out of memory errors when working with the wine ontology?</strong><br />
      <strong>A:</strong>
      The wine/food ontology is specifically designed to exercise all OWL/DL constructs. The
      Jena rule-based reasoner only supports the OWL/lite subset of OWL/Full and has scaling
      problems with some of the constructs used in the wine ontology. If you need full
      reasoning support for the wine (or similar) ontologies then use a full DL reasoner
      such as Pellet, which can be accessed via the DIG interface or directly using the
      Pellet-provided OntModelSpec. If you only need to do things like traverse the class
      hiearchy and inference over RDFS plus OWL property relations is enough for you, then the
      OWL micro reasoner may be an option.</p>

  <p id="reasoner-5"><strong>Q: What causes the error
    &quot;<code>java.lang.UnsupportedOperationException: this is not a URI node</code>&quot; in the DIG reasoner?</strong>
    <br />
    <strong>A:</strong>
    This is a known problem with the Jena 2.1 release. Please get the latest version of Jena (a later
    release, if there is one, or get the sources from CVS and
    <a href="#general-3">build a new copy of <code>jena.jar</code></a>.)
  </p>

  <p id="reasoner-6"><strong>Q: I want to use my own custom rules to extend an existing RDFS or OWL
Schema, what do I do? </strong>
    <br />
    <strong>A:</strong>
    The easiest way to do this is to define your rule set. You can use the
    <code>@include</code> directive at the top of your rules to include the RDFS (or OWL) rules
    first. Then create a 
    <a href="javadoc/com/hp/hpl/jena/reasoner/rulesys/GenericRuleReasoner.html">GenericRuleReasoner</a>
    which you can use to build an InfModel such as an
    <a href="javadoc/com/hp/hpl/jena/ontology/OntModel.html">OntModel</a> (by attaching the
    reasoner to your <a href="javadoc/com/hp/hpl/jena/ontology/OntModelSpec.html">OntModelSpec</a>).
    See <a href="inference/index.html#RULEconfiguration">GenericRuleReasoner
    configuration</a> for an example of how to parse custom rules.
    </p>

    <p>
    Some important guidelines:</p>
    <ul>
    <li>if you're using OWL rules: <code>setOWLTranslation(true)</code> on the reasoner</li>
    <li>if you're using RDFS or OWLMicro: <code>setTransitiveClosureCaching(true)</code></li>
    <li>make your own rules backwards unless you know what you are doing</li>
    </ul>

    <p>
    You may only use backward rules in this configuration because the RDFS 
    and OWL rules use a mix of forward and backward chaining and the rule 
    system architecture is a pure dataflow - the forward rules don't call 
    the backward rules. Thus any forward rules will only see those parts of
    the RDFS/OWL inferences which are computed forwards. Rather than
    have to be familar with those details it is easiest to simply write your
    own rules as backward ones.
    </p>

    <p>
    An alternative is to use a layered architecture - build your
    generic rule InfModel on top of a separate RDFS/OWL InfModel. That has
    higher overhead but then your own rules are unrestricted.
    </p>

    <h3>Ontology API</h3>
<p id="ontology-0"><strong>Q: Why doesn't <code>listClasses()</code> (or <code>listProperties()</code>/<code>listIndividuals()</code>,
  etc) work?</strong><br />
  <strong>A:</strong> It does work. Extensive unit tests are used to check the correctness of Jena,
  and are included in the downloaded source code for your reference. If <code>listClasses()</code>,
  or a similar method, is not producing the answers you expect, or no answers
  at all, you should first check that your model is correctly defined. Print a
  copy of your model as a debug step, to see if the URI's match up (e.g, if you
  are expecting resource x to be an individual of class Y, check that the rdf:type
  of x is the same as the URI of the class declaration for Y). A common problem
  is that relative URI's change depending where you read the model from. Try adding
  an <code>xml:base</code> declaration to the document to ensure that URI's are
  correctly specified.</p>

  <p id="ontology-1">
      <strong>Why doesn't <code>listProperties()</code> return any results when <code>listObjectProperties()</code> (or
      <code>listDatatypeProperties()</code>) does?</strong><br />
      <strong>A:</strong> The method <code>OntModel.listObjectProperties()</code> returns those resources from
      the OntModel with <code>rdf:type rdf:Property</code>.  Under the OWL semantic theory, this is true
      of <code>owl:ObjectProperty</code> since ObjectProperty is a sub-class of Property.  However, unless
      an OWL reasoner is used with an OWL model (or a DAML reasoner with a DAML model, etc), this inferred
      <code>rdf:type</code> statement is not visible.  Therefore, with no reasoner, the OntModel
      cannot tell that an ObjectProperty is a Property.  The solution is to construct the OntModel
      with an appropriate reasoner.  If, for some application reason, using a reasoner is not possible
      then users should be prepared to list the various property types separately.  Note also the
      next question.
  </p>
  <p id="ontology-2">
      <strong>Why are my transitive properties (or symmetric properties or inverse functional
      properties) missing when I call <code>listObjectProperties()</code>?</strong><br />
      <strong>A:</strong> This is essentially the same problem as the <a href="#ontology-1">
       previous FAQ</a>.  Without an OWL reasoner, the model cannot tell that an <code>owl:TransitiveProperty</code>
       is also an <code>owl:ObjectProperty</code> and an RDF property. The same solution advice
       applies as with the previous question.
  </p>

<p id="ontology-3">
  <strong>Q: Why does <code>.as(&nbsp;OntProperty.class&nbsp;)</code> fail with
  <code>ConversionException</code> on SymmetricProperty (or other property types)?</strong><br />
  <strong>A:</strong> This is a slightly tricky issue.  Internally, <code>.as()</code> calls the <em>supports</em> check,
  which tests whether the node that is being converted is a common flavour of property.
  Strictly, the only necessary test should be '<code>has rdf:type rdf:Property</code>',
  because that is entailed by all of the other property types.  However, that requires
  the user to use a model with a reasoner, and some don't want to (for good reasons, e.g. building an editor).
  The other position is to test for all the possible variants of property: object property,
  datatype property, annotation, ontology, transitive, functional, inverse functional, etc etc.
  The problem with this is that it duplicates the work of the reasoner, and my expectation was that
  most people would be running with a reasoner.  Thus my code would be duplicating the functionality
  of the reasoner, which is bad design. The compromise solution was to make the supports check test
  for the common (top level) property types.  Users who aren't using the reasoner,
  can either test explicitly for the other property types they expect to encounter (e.g. SymmetricProperty),
  or can turn off the supports check by setting
  <a href="javadoc/com/hp/hpl/jena/ontology/OntModel.html#strictMode()">strict mode</a> to false on the model.
</p>

<p id="ontology-4"><strong>Q: Why doesn't the ontology API handle <code>sub-class</code>
    (or <code>sub-property</code>, <code>domain</code>, <code>range</code>, etc)
      relationships in a DAML model?</strong><br />
      <strong>A:</strong> These relationships are handled correctly, but the results you see are dependent on the
      model configuration.  The DAML specification includes a number of aliases for RDFS constructs to
      copy them into the DAML+OIL namespace. This means that, for a DAML processor, <code>daml:subClassOf</code>
      and <code>rdfs:subClassOf</code> are equivalent.  This is declared by means of a
      <code>daml:samePropertyAs</code> in the daml+oil.daml specification document.  Without a reasoner
      attached to the model, the ontology API will not recognise the equivalence with <code>rdfs:</code> properties.
      Thus, if you are not seeing the expected results when processing a DAML ontology,
      it is likely that your ontology file contains, for example, <br />
      <code>&lt;daml:Class rdf:ID="A"&gt; &lt;rdfs:subClassOf rdf:resource="B" /&gt; ...</code> <br />
      To fix this, either ensure that the ontology consistently uses <code>daml:</code> relationships,
      or declare the ontology model with the DAML micro rule-reasoner: <br />
      <code>OntModel m = ModelFactory.createOntologyModel( OntModelSpec.DAML_MEM_RULE_INF, null );</code>
    </p>

<p id="ontology-5"><strong>Q: I don't understand very clearly the difference between
the various <code>OntModel</code> model profiles.</strong><br />
<strong>A:</strong>
OK, here's how it works.  The ontology API is designed to provide a single
set of convenient programming abstractions for a Jena model that contains
an ontology in either RDFS, DAML or (the various flavours of) OWL.
Each of these languages is structurally similar, but differ in detail.
So, a class is declared variously as <code>owl:Class</code>,
<code>rdfs:Class</code> and <code>daml:Class</code>.
Hence one role of the ont model profiles (i.e. <code>OntModelSpec</code> objects) is to specify the
details of which syntax is being used.</p>
<p>
Second, ontology models can be composed of many sub-models when an ontology
<em>imports</em> another ontology. These sub-models have to be stored
somewhere, perhaps in memory or in a database.  The profile contains a
<code>ModelMaker</code>, which provides the
<code>OntModel</code> with new sub-models on demand,
to contain the imported ontology documents.
</p><p>
Third, ontologies can be made richer by including the entailments of
the ontology assertions, given the semantics of the language. To do this,
you need a reasoner. Since Jena provides an open, extensible architecture
for adding reasoners, and some built-in pre-defined reasoners, the
model profile specifies which reasoner, if any, that model will use.
</p><p>
These are the main components of an <code>OntModelSpec</code>.  You can construct each
of these elements independently, programatically or with RDF,
but we have anticipated some common choices.
So we provide some
built-in standard profiles.  These have names like <code>OWL_MEM</code>, or <code>RDFS_MEM_RDFS_INF</code>.
The first component of the name is the syntax (OWL, RDFS etc). The second
component is the model-maker strategy (MEM means in-memory models). The
third component, which may be absent, specifies the reasoner.
<code>OWL_MEM</code> has no reasoner, <code>RDFS_MEM_TRANS_INF</code> uses a
simple reasoner that computes transitive closure on the class and property hierarchies, but nothing else.
</p>

<h3>Database and persistence</h3>
<p id="db-0"><strong>Q: Why do I get an exception when trying to create a new persistent model?</strong><br>
  A: If the exception has to do with the database lock, see the question on
<a href="#dblock">locking</a>. Otherwise, assuming that your program uses correct methods to create the model (see
examples in the database <a href="DB/creating-db-models.html">How To Create Persistent Models</a>), it may be that
your database files are corrupted. Jena2 does <i>not</i> do a good job in
checking the validity of the database. It makes a cursory check that some
required tables exist but does not check that the tables contain valid data. If
you suspect your database has been corrupted, you may invoke
<code>cleanDB()</code> on a DBConnection object
prior to creating your model. This removes all Jena2 tables from a database.
Warning: this removes any other existing Jena2 models from the database so make sure
that this is what you want to do. </p>

  <p id="db-1"><strong>Q: Why do I run out of memory when trying to list statements in a persistent
  model?</strong><br>
  A: Jena2 uses the JDBC interface for accessing databases. The JDBC
  specification has no cursors. Consequently, when a query is processed by JDBC,
  the entire result set is returned from the database at once and the application program then iterates
  over the in-memory result set. If the result set is large, as is often the case
  when listing all statements of a large model, it may exceed the heap size of
  the Java virtual machine. If you suspect this is happening, you might try to
  increase the heap size of the Java virtual machine (<code>-vmargs
  -Xmx500M</code> for a 500 MB heap size). If this does not help, there is no
  other work-around and the program should be recoded.</p>

<p id="db-2"><strong>Q: Has Jena2 persistence been ported to other database engines and platforms
  besides those officially supported?</strong><br>
  A: The Jena team  supports Jena2 persistence on the databases and operating
systems listed in the <a href="DB/index.html">Database documentation</a>. These 
include MySQL, HSQLDB, PostgreSQL, Oracle, SQL Server.
Other users have had success porting Jena2 to other databases and platforms.
Jena2 has been ported to IBM's DB2 database. Contact
<a href="mailto:zhabglj@us.ibm.com">Liang-Jie Zhang</a> for details. </p>

<p id="db-3"><strong>Q: Is there a limit on
the number of models in a database?</strong><br>
  <strong>A:</strong> The limit depends on the Jena database (schema) configuration and the
database engine (MySQL, PostgreSQL, Oracle, etc). Recall that a Jena model may
either be stored separately in its own database tables (the default) or,
alternatively, in tables that are shared with other models (see <i>
StoreWithModel</i> in the <a href="DB/options.html">options</a> for
persistent models). Also, a Jena model is identified internally by a 32 bit
integer. Consequently the maximum number of models is limited either by the
maximum number of tables allowed in a database (which depends on the database
engine) or by the maximum value of a 32 bit integer, i.e., 2G.</p>

<p id="db-4"><strong>Q: Why am I getting an exception on failure to lock or unlock the database?</strong><br>
  <strong>A:</strong> The Jena2 storage subsystem uses a lock internally to
  implement a critical section for operations that modify the database structure
  (create/delete tables). The lock is implemented as a database table, i.e., if
  the table exists in the database, the lock is held. Normally, this lock
  should be transparent to applications. But if an application has an exception
  while in a critical section, the database may remain locked for subsequent
  applications. In this case, a user must manually unlock the database either by
  calling DriverRDB.unlockDB() or by deleting the table (Jena_Mutex) from the database.</p>

<p id="db-5"><strong>Q: How do I access the Jena database tables?</strong><br>
  <strong>A:</strong> The Jena2 database tables are not intended for direct
access
  by Jena users or applications. The database tables are created, deleted and manipulated
  through the Jena API methods. For example, creating a database model may cause tables
  to be added to tbe database. So, the user need not directly view or access the Jena
  database. Also, Jena encodes RDF statements, resources and literals in a way that
  makes them difficult to view or query using conventional (SQL) database tools. Users who
  are interested in the Jena2 database structure and value encoding can find details
  in the <a href="DB/layout.html">layout</a> documentation. </p>

<h3>XML serialisation (reading and writing)</h3>

<p id="xml-1"><strong>Q: Why does my output use <code>&lt;rdf:Description&nbsp;...&gt;</code>
    when I want output like <code>&lt;owl:Class&nbsp;...&gt;</code>?</strong><br />
<strong>A:</strong> This is the raw form of the RDF serialisation into XML. In terms of RDF's
information model, it expresses the same semantics as the compressed form. So the following
fragments are equivalent (in RDF terms):</p>
  <pre>  &lt;rdf:Description rdf:about="#foo"&gt;
    &lt;rdf:type rdf:resource=&quot;http://www.w3.org/2002/07/owl#Class&quot;&gt;
  &lt;/rdf:Description&gt;

  &lt;owl:Class rdf:about=&quot;#foo&quot; /&gt;</pre>
<p>However, the second is considerably easier for human readers to read, and tends to
  be the form most people come across when reading OWL or DAML ontologies, for example.  The default
  output format is <code>RDF/XML</code>, the abbreviated format is <code>RDF/XML-ABBREV</code>.
  To change from the default output style, pass the required output format to the
  <a href="javadoc/com/hp/hpl/jena/rdf/model/Model.html#write(java.io.OutputStream,%20java.lang.String)">Model.write</a>
  method:
</p>
<pre>  yourModel.write( yourOutputStream, "RDF/XML-ABBREV" );</pre>
<p>Note that the abbreviated form requires the writer to do much more work (multiple passes are
  needed over the RDF model, to see which abbreviation rules can apply). Hence it may be
  inappropriate for large models.  In particular, the abbreviated form is
    <strong>not</strong> recommended for serialising
  large models from a persistent database to RDF XML. More details on controlling the
  precise behaviour of the writer, including turning on and off abbreviation rules, are
  in the <a href="IO/iohowto.html#output">I/O howto</a>.</p>

<p id="xml-2"><strong>Q: Why does my XML output contain strange prefixes <code>j.0</code>,
  <code>j.1</code>, etc?</strong><br />
<strong>A:</strong> XML's <a href="http://www.w3.org/TR/REC-xml-names/">namespace mechanism</a>
is used in serialised RDF/XML to make legal XML element names from URI's. XML elements are not
permitted to contain certain characters, many of which are required when making URI's. For example,
<code>http://example.com/test#SomeClass</code> is not a legal element name. We can make the
name XML-legal by ensuring all of the non-<em>ncname</em> characters (ncname denotes
characters that can form legal XML element names) appear in the XML namespace prefix. So,
<code>&lt;http://example.com/test#TestClass&gt;</code> is not legal, but
<code>&lt;ns:TestClass xmlns=&quot;http://example.com/test#&quot;&gt;</code> is legal.
Jena's XML writer will add xmlns prefixes as necessary to make your XML output
conform to the rules of correct XML. This may mean creating new prefix names. Jena's
convention is to name these new prefixes <code>j.0</code>, <code>j.1</code>, etc.
If you want these prefixes to have more meaningful names, before you write the model
call <a href="javadoc/com/hp/hpl/jena/shared/PrefixMapping.html#setNsPrefix(java.lang.String,%20java.lang.String)"><code>setNsPrefix</code></a>
on your model to assign your preferred prefix to a given URI.</p>

<h3>SPARQL and query processing</h3>
<p>See the <a href="http://openjena.org/ARQ/Tutorial/index.html">SPARQL Tutorial</a></p>

<p id="sparql-0"><strong>Q: How do I do test substrings of literals?</strong><br>
<strong>A:</strong> SPARQL provides REGEX.
See the <a href="http://openjena.org/ARQ/FAQ.html">ARQ FAQ</a> for details.<p>&nbsp;</p>

</div><!-- end #content -->

</td>
</tr>
</table>
</div> <!-- end #main -->

<div id="footer">
&nbsp;
</div>

<div id="logos">
<div class="left">
<a href="http://www.w3.org/RDF/" title="RDF Resource Description Framework">
  <img border="0" src="images/rdf_w3c_icon.gif" alt="Resource Description Framework">
</a>
</div>

<div class="right">
  <a href="http://sourceforge.net/projects/jena"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=40417&type=13" width="120" height="30" border="0" alt="Get Jena at SourceForge.net. Fast, secure and Free Open Source software downloads" /></a>

<!--
Hosted by:
<a href="http://sourceforge.net/projects/jena" title="SourceForge">
< !- -
  <img src="http://sourceforge.net/sflogo.php?group_id=40417&amp;type=1"
       border="0"
       alt="sourceforge.net" />
-->
  <img src="images/sflogo-type1.png" border="0" alt="sourceforge.net"/>
</a>
</div>

</div>

</body>
</html>
